Version: Next

key-management-providers

Key Management Provider

NOTE: KeyManagementProvider replaces CertificateStore which is now DEPRECATED. See migration guide.

A KeyManagementProvider (KMP) represents key(s) and/or certificate(s) that are consumed by a verifier. KMP contains various providers for different use cases. Each provider is responsible for defining custom configuration and providing a set of public keys and/or x.509 certificates. Notation and Cosign verifiers can consume KMP resources to use during signature verification. Please refer to respective Notation and Cosign verifier documentation on how to consume KMP.

Key Management Provider
Table of Contents
Scope
Utilization in Verifiers
- Examples
Configuration guidelines
- Inline
  - Template
- Azure Key Vault
  - Template
Limitation
Status
Resource Create/Update
Migrating from CertificateStore to KMP

Scope

Key Management Provider can be defined as cluster-wide resources(using the kind KeyManagementProvider) or namespaced resources(using the kind NamespacedKeyManagementProvider).

Utilization in Verifiers

The KeyManagementProvider serves primarily as a reference to key/certificate stores in Verifier CRs. Given that the Key Management Provider can exist either cluster-wide or within a namespace, users need to include the appropriate namespace prefix when referencing the KMP in Verifier CRs. To reference a namespaced KMP, the format should be namespace/kmp-name. Conversely, to reference a cluster-wide KMP, the format should simply be kmp-name.

In general, there are 2 valid use cases. One is a namespaced verifier references a namespaced KMP within the same namespace or a cluster-wide KMP. The other is a cluster-wide verifier references a cluster-wide KMP.

Examples

Scenario 1: A namespaced verifier referencing both namespaced KMP and cluster-wide KMP.

apiVersion: config.ratify.deislabs.io/v1beta1
kind: NamespacedVerifier
metadata:
  name: verifier-notation
  namespace: default
spec:
  name: notation
  artifactTypes: application/vnd.cncf.notary.signature
  parameters:
     verificationCertStores:
       certs:
         - default/ratify-notation-inline-cert-0
         - ratify-notation-inline-cert-0
  # skip irrelevant fields

Scenario 2: A cluster-wide verifier referencing cluster-wide KMP.

apiVersion: config.ratify.deislabs.io/v1beta1
kind: Verifier
metadata:
  name: verifier-notation
spec:
  name: notation
  artifactTypes: application/vnd.cncf.notary.signature
  parameters:
     verificationCertStores:
       certs:
         - ratify-notation-inline-cert-0
  # skip irrelevant fields

Configuration guidelines

Inline

Template

A provider that can specify a single certificate or key. The content is expected to be defined inline in the resource configuration.

apiVersion: config.ratify.deislabs.io/v1beta1
kind: KeyManagementProvider # NamespacedKeyManagementProvider has the same spec.
metadata:
  name:  # a unique name
spec:
  type: inline
  parameters:
    contentType: # REQUIRED: [string] (key, certificate)
    value: # REQUIRED: [string] value of content  
status:
  error:            # error message if the operation failed
  issuccess:        # boolean that indicate if operation was successful
  lastfetchedtime:  # timestamp of last attempted fetch operation
  properties: # provider specific properties of the fetched certificates/keys. If the current fetch operation fails, this property displays the properties of last successfully cached certificate/key

Name	Required	Description	Default Value
contentType	yes	'key' or 'certificate'. Describes content type	""
value	yes	string content	""

Azure Key Vault

Template

apiVersion: config.ratify.deislabs.io/v1beta1
kind: KeyManagementProvider
metadata:
  name: # a unique name
spec:
  type: azurekeyvault
  parameters:
    vaultURI: # REQUIRED: [string], azure key vault URI
    tenantID: # REQUIRED: [string], Azure tenant ID
    clientID: # REQUIRED: [string], client ID of the identity to use to access key vault
    certificates: # OPTIONAL: [list], certificates in key vault to fetch
      - name: # REQUIRED: [string], certificate name
        version: # OPTIONAL [string], version identifier
    keys: # OPTIONAL: [list], keys in key vault to fetch
      - name: # REQUIRED: [string], key name
        version: # OPTIONAL [string], version identifier 

Name	Required	Description	Default Value
vaultURI	yes	Azure key vault URI	""
tenantID	yes	Azure tenant ID	""
clientID	yes	client ID of the identity to use to access key vault	""
certificates	no	list of certificates in key vault to fetch	[]
certificates[*].name	yes	certificate name (as shown in key vault)	""
certificates[*].version	no	version identifier (as shown in key vault). If not provided, latest version will be used.	""
keys	no	list of keys in key vault to fetch	[]
keys[*].name	yes	key name (as shown in key vault)	""
keys[*].version	no	version identifier (as shown in key vault). If not provided, latest version will be used	""

Limitation

If a key/certificate is in disabled state, KMP resource creation will FAIL. Users must remove reference to a disabled Key/Certificate or re-enable in Azure Key Vault.
Ratify does NOT yet support periodic refresh and polling of certificates/keys. If the default latest version changes, object is disabled/expired, or deleted, Ratify will only become aware once the KMP resource is reconciled (edited, deleted, added).
If keys are configured, the managed identity with clientID specified MUST be assigned the correct permissions to list, view, and download keys in the configured Key Vault.
Azure Key Vault Certificates are built on top of keys and secrets. When a certificate is created, an addressable key and secret are also created with the same name. Ratify requires secret permissions to retrieve the public certificates for the entire certificate chain. Please set private keys to Non-exportable at certificate creation time to avoid security risk. Learn more about non-exportable keys here
Certificate/Key MUST be in PEM format. PKCS12 format with nonexportable private keys can NOT be parsed due to limitation of Golang certificate library.
Refer to Azure Key Vault setup guide ratify-on-azure quick start.

Note: If you were unable to configure certificate policy, please consider specifying the public root certificate value inline using an inline key management provider to reduce risk of exposing a private key.

Status

Get an overview of KMPs status:

kubectl get keymanagementproviders.config.ratify.deislabs.io

Get specific status of each certificate/key fetched in a single KMP

kubectl get keymanagementproviders.config.ratify.deislabs.io/<INSERT KMP NAME>

Resource Create/Update

During KMP resource creation, the resource may successfully create even though the provider-specific schema is invalid.

For example:

The contentType field is missing for the inline KMP.
The vaultURI is missing in the Azure Key Vault KMP.

Please follow the steps here to confirm status of the KMP.

Migrating from `CertificateStore` to KMP

CertificateStore resource is deprecated starting in v1.2.0. Ratify will continue to support CertificateStore functionality until v2.0.0 at which time it will be removed.

All existing functionality available in CertificateStore is available in KeyManagementProvider.

Inline CertificateStore to Inline KMP

CertificateStore	KeyManagementProvider
`.parameters.value`	`.parameters.value`
`.parameters.contentType`	N/A

contentType is required and must be key OR certificate. This MUST be added when migrating.

Azure Key Vault CertificateStore to Azure Key Vault Key Management Provider

CertificateStore	KeyManagementProvider
`.parameters.clientID`	`.parameters.clientId`
`.parameters.tenantID`	`.parameters.tenantID`
`.parameters.vaultURI`	`.parameters.vaultURI`
`.parameters.certificates`	`.parameters.certificates[]` String content is now defined objects
`.parameters.certificates[*].certificateName`	`.parameters.certificates[*].name`
`.parameters.certificates[*].certificateVersion`	`.parameters.certificates[*].version`

Notation Verifier

Notation verifier's verificationCertStores array must be updated to reference the KeyManagementProvider resource name